MarkLogic Server 11.0 Product Documentation
POST /v1/documents?extension={ext}

Summary

Create a new document with a server-generated database URI.

URL Parameters
extension	Specifies a URI extension to use when the document URI is generated by MarkLogic Server. The generated URI will end with "." plus this extension. This parameter is required.
category*	The category of data to insert or update. Category may be specified multiple times to insert or replace any combination of content and metadata. Valid categories: `content` (default), `metadata`, `metadata-values`, `collections`, `permissions`, `properties`, and `quality`. Use `metadata` to update all metadata. See the Usage notes below.
directory?	Specifies a directory prefix to use when the document URI is generated by MarkLogic Server. If an `extension` parameter is present and there is no `directory` parameter, then no directory prefix is included in the generated URI. If the request includes a `directory` parameter, it must also include an `extension` parameter. You cannot use this parameter with the `uri` parameter.
database?	Perform this operation on the named content database instead of the default content database associated with the REST API instance. Using an alternative database requires the "eval-in" privilege; for details, see Security Requirements in the REST Application Developer's Guide.
format?	The content type of the metadata in the request body. Specifying a format overrides the Content-Type request header value when inserting only metadata. For details, see the Usage Notes and Controlling Input and Output Content Type in the REST Application Developer's Guide. This parameter only affects metadata, not document content.
collection*	The URI of a collection to which to add the document. Use this parameter only when the request includes content; see the Usage notes for details.
quality?	The quality of this document. A positive value increases the relevance score of the document in text search functions. The converse is true for a negative value. The default value is 0. Use this parameter only when the request includes content; see the Usage notes for details.
perm:{role}*	Assign the document to the listed role, with the permission given in the parameter value. For example, `perm:editor=update`. Valid values: `read, update, execute`. Only the named role is changed. Unspecified roles retain their current permissions. Use this parameter only when the request includes content; see the Usage notes for details.
prop:{name}*	Attach the named property to the document, with the given property value. For example, `prop:decade=70`. The property name must be an `xs:NCName`. If the property already exists, its value is replaced. Only the named property is modified. Unspecified properties are unaffected. Use this parameter only when the request includes content; see the Usage notes for details.
value:{key}*	Attach the specified values metadata to the document, where the key is as given after the `value:` prefix and the value is the request parameter value. For example, `value:a=1`. Only the specified key's value is changed. Use this parameter only when the request includes content; see the Usage Notes for details.
extract?	For binary content, whether or not to extract metadata, and whether to store the extracted metadata as properties or in a separate XHTML document. Accepted values: `properties` or `document`. See note below.
repair?	The type of XML repair to perform on the input content. Accepted values: `full` (default) or `none`. Use `full` to request the server to repair malformed input XML. Use `none` to request the server to reject malformed input XML. If repair results in multiple root nodes, the update is rejected.
transform?	Names a content transformation previously installed via the `/transforms` service. The service applies the transformation to the content prior to updating or inserting the document or metadata.
trans:{name}*	A transform parameter name and value. For example, `trans:myparam=1`.
forest-name?	Specifies the name of a forest into which this document is inserted. If the document already exists in the database, it remains in its existing forest. If no such forest exists or if no such forest is attached to the context database, an error is raised. If the document already exists and the forest in which it is stored is set to delete-only, an error is raised.
txid?	The transaction identifier of the multi-statement transaction in which to service this request. Use the `/transactions` service to create and manage multi-statement transactions.
lang?	This parameter is deprecated and will be ignored if present. When ingesting JSON content, this parameter specifies the JSON content language. Accepted values: Any value accepted in the `xml:lang` attribute.

Request Headers
Content-Type?	The MIME type of the data in the request body. See the usage notes for details.

Response Headers
Location?	If the request successfully creates a new document with a server assigned URI, then the `Location` contains a reference to the /documents service that you can use to retrieve the new document. That is, a reference of the following form is returned: `/v1/documents?uri=generated-uri`.

Response

Upon success, MarkLogic Server responds with 201 (Document Created) or 204 (Updated or Unchanged).

Required Privileges

This operation requires the rest-writer role, or the following privileges:

http://marklogic.com/xdmp/privileges/rest-writer

http://marklogic.com/xdmp/privileges/rest-reader

Usage Notes

Use this form of POST /v1/documents to create a new document with a server-generated URI. The request can optionally include metadata. For all other document and metadata creation or update operations, see PUT /v1/documents or the other forms of POST /v1/documents.

To create a new document with a server-assigned URI:

Specify a URI extension using the extension parameter.
Optionally, specify a directory prefix using the directory parameter.
Include content as one of the category parameter values.

The request body must be either the document content or a multi-part message that includes both metadata and content, as described below. The server-generated URI is returned in the Location response header.

You can create content and metadata in a single request in two ways:

Construct a multipart/mixed request with the metadata and content in the request body parts.
Place the content in the request body and specify metadata using the collection, quality, perm, value:{key}, and prop request parameters.

You cannot combine these methods: Metadata request parameters are ignored when the request body includes metadata. You cannot insert metadata without also inserting content.

When using a multipart/mixed request to insert content and metadata in the body of a single request, put the metadata in the first part and specify its content type (XML or JSON) using the Content-type header of the part or the format request parameter. Put the content in the second part and set the Content-type header the appropriate MIME type for the content.

When including metadata in the request body, supply metadata specified in category parameters in a single XML or JSON container. For details, see Loading Content into the Database in the REST Application Developer's Guide.

For a binary document, extracting metadata as properties replaces any existing properties on the document. Extracting metadata to a document creates an XHTML document that differs from the input document only by having a xhtml file name extension. If CPF is installed in the database, the XHTML document includes a link to the binary document. For details, see Extracting Metadata and Text From Binary Documents in the Search Developer's Guide.

The documents you create with the MarkLogic REST API have the default permissions for the user and document as well as any permissions that you set explicitly. The permissions must include at least one update permission. For more detail, see Controlling Access to Documents and Other Artifacts in the REST Application Developer's Guide.

When updating document permissions, the permissions must include at least one update permission.

The metadata-values category represents "metadata fields" document metadata. For more details, see Metadata Fields in the Administrator's Guide.

Example

curl --anyauth --user user:password -X POST -d@'./my-content' -i \
  -H "Content-type: application/xml" \
  'http://localhost:8000/v1/documents?extension=xml&directory=/plays/'

==> Create a document from the XML in ./my-content, with a server
    generated URI. The URI is rooted at the directory "/plays/" and
    has an ".xml" suffix. The generated URI is returned in the Location
    response header. MarkLogic Server returns a response similar to 
    the following:

Content-type: application/xml
Server: MarkLogic
Content-Length: 211
Connection: Keep-Alive
Keep-Alive: timeout=5

HTTP/1.1 201 Document Created
Location: /plays/14993128029398656352.xml
Server: MarkLogic
Content-Length: 0
Connection: Keep-Alive
Keep-Alive: timeout=5